home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 2000 August: Tool Chest / Dev.CD Aug 00 TC Disk 2.toast / pc / sample code / interapplication comm / moreosl / moredebugging / morebblog.h < prev   
Encoding:
C/C++ Source or Header  |  2000-06-23  |  5.9 KB  |  183 lines
  1. /*
  2.     File:        MoreBBLog.h
  3.  
  4.     Contains:    Module to log debug traces to BBEdit.
  5.  
  6.     Written by:    Quinn
  7.  
  8.     Copyright:    Copyright © 2000 by Apple Computer, Inc., all rights reserved.
  9.  
  10.                 You may incorporate this Apple sample source code into your program(s) without
  11.                 restriction. This Apple sample source code has been provided "AS IS" and the
  12.                 responsibility for its operation is yours. You are not permitted to redistribute
  13.                 this Apple sample source code as "Apple sample source code" after having made
  14.                 changes. If you're going to re-distribute the source, we require that you make
  15.                 it clear in the source that the code was descended from Apple sample source
  16.                 code, but that you've made changes.
  17.  
  18.     Change History (most recent first):
  19.  
  20.          <2>     20/3/00    Quinn   Expanded and clarified comments.
  21.          <1>      6/3/00    Quinn   First checked in.
  22. */
  23.  
  24. #pragma once
  25.  
  26. /////////////////////////////////////////////////////////////////
  27.  
  28. // MoreIsBetter Setup
  29.  
  30. #include "MoreSetup.h"
  31.  
  32. // Mac OS Interfaces
  33.  
  34. #include <AppleEvents.h>
  35.  
  36. /////////////////////////////////////////////////////////////////
  37.  
  38. #ifdef __cplusplus
  39. extern "C" {
  40. #endif
  41.  
  42. // Overall Architecture
  43. // --------------------
  44. // This module is designed to allow you to log textual data to BBEdit.
  45. // I used it primarily in MoreOSL to log the progress of my OSL resolution
  46. // and event dispatching.  The nice thing about this is that, when an
  47. // event fails, you can consult the log to find the failure point quickly.
  48. // This is tricky to do otherwise because OSL involves many callbacks,
  49. // which make it hard to follow the flow of control in the debugger.
  50. //
  51. // You can use these routines in any structure (there’s no strong
  52. // relationship between the routines) by I typically use the following
  53. // approach:
  54. //
  55. //   1.    At application startup, call BBLogStart.
  56. //     2.    The debug version of the application has a global "debug"
  57. //        property that scripts can get and set to control the state
  58. //        of logging.  The application’s property setter can control 
  59. //        whether this module logs anything by calling BBLogSetState.
  60. //     3.    On entry to a routine, use BBLogLine to log the routine’s
  61. //      name and BBLogIndent to make the nested log information be
  62. //        nested in the log.
  63. //   4. On exit to a routine, use BBLogOutdentWithErr to both
  64. //        un-indent and log the error result for the routine.
  65. //     5. Inside a routine, use the other routines to log specific
  66. //        data points.  I commonly log the value of incoming parameters
  67. //        at the begging of the routine and the value of outgoing parameters
  68. //        at the end.  I also log important intermediate results.
  69. //
  70. // The following is an imaginary Apple event handler that is marked up
  71. // using BBLog:
  72. //
  73. //    static pascal OSErr MyHandler(const AppleEvent *theEvent, AppleEvent *theReply, UInt32 handlerRefCon)
  74. //    {
  75. //        OSStatus err;
  76. //        AEDesc      dirObjDesc;
  77. //        AEDesc      resolvedDirObToken;
  78. //    
  79. //        BBLogLine("\pAEDispatcher");
  80. //        BBLogIndent();
  81. //        BBLogAppleEvent("\ptheEvent", theEvent);
  82. //        BBLogLong("\phandlerRefCon", handlerRefCon);
  83. //    
  84. //        [.. get the direct object ...]
  85. //
  86. //        err = AEResolve(&dirObjDesc, ..., &resolvedDirObToken);
  87. //        if (err == noErr) {
  88. //            BBLogDesc("\presolvedDirObToken", &resolvedDirObToken);
  89. //        }
  90. //
  91. //        [... handle the event ...]
  92. //        
  93. //        BBLogAppleEvent("\p<theReply", theReply);
  94. //        BBLogOutdentWithErr(err);
  95. //        
  96. //        return err;
  97. //    }
  98. //
  99. // For more examples, take a look at "MoreOSL.c".
  100. //
  101. // To assist in sensible logging, this module installs a bunch of coercion
  102. // handlers to coerce various built-in types to text.  These handlers are
  103. // only installed in the debug version.  You may want to use these handlers
  104. // in other situations.
  105.  
  106. // The following routines are defined only if you’re compiling with
  107. // debugging enabled.  Otherwise they are all stubbed out with macros.
  108.  
  109. #if MORE_DEBUG
  110.  
  111.     extern pascal void BBLogStart(Boolean logging);
  112.         // Starts the BBEdit logging module and sets the
  113.         // current logging state (if logging is true, logging
  114.         // is on, otherwise it’s off).  The rest of the routines
  115.         // in this module only produce output is logging is on.
  116.         // 
  117.         // If logging is true, this routine creates a new window in
  118.         // BBEdit for the log data.
  119.  
  120.     extern pascal void BBLogSetState(Boolean logging);
  121.         // Turns logging on or off.
  122.         
  123.     extern pascal void BBLogText(void *textPtr, Size textSize);
  124.         // Logs the text buffer to BBEdit, without any formatting
  125.         // or interpretation.
  126.         
  127.     extern pascal void BBLogLine(ConstStr255Param str);
  128.         // Logs a line of text to BBEdit, adding a time stamp
  129.         // at the front and a CR at the end.  It also indents
  130.         // the line based on the current indent level.
  131.  
  132.     extern pascal void BBLogIndent(void);
  133.         // Increases the current indent level by 1.
  134.         
  135.     extern pascal void BBLogOutdent(void);
  136.         // Decreases the current indent level by 1.
  137.         
  138.     extern pascal void BBLogOutdentWithErr(OSStatus errNum);
  139.         // Decreases the current indent level by 1 and logs
  140.         // a line of text of the form:
  141.         //
  142.         //     err=<decimal representation of errNum>
  143.  
  144.     extern pascal void BBLogAppleEvent(ConstStr255Param tag, const AppleEvent *theEvent);
  145.         // Logs a line of text of the form:
  146.         // 
  147.         //     <tag>=<text description of theEvent>
  148.         
  149.     extern pascal void BBLogLong(ConstStr255Param tag,       SInt32 l);
  150.         // Logs a line of text of the form:
  151.         // 
  152.         //     <tag>=<decimal representation of l>
  153.  
  154.     extern pascal void BBLogDesc(ConstStr255Param tag,       const AEDesc *desc);
  155.         // Logs a line of text of the form:
  156.         // 
  157.         //     <tag>=<text representation of desc>
  158.  
  159.     extern pascal void BBLogDescType(ConstStr255Param tag,   DescType theType);
  160.         // Logs a line of text of the form:
  161.         // 
  162.         //     <tag>='<theType>'
  163.  
  164. #else
  165.  
  166.     #define BBLogStart(logging)
  167.     #define BBLogSetState(logging)
  168.     #define BBLogText(textPtr, textSize)
  169.     #define BBLogLine(str)
  170.     #define BBLogIndent()
  171.     #define BBLogOutdent()
  172.     #define BBLogOutdentWithErr(errNum)
  173.     #define BBLogAppleEvent(tag, theEvent)
  174.     #define BBLogLong(tag, l)
  175.     #define BBLogDesc(tag, desc)
  176.     #define BBLogDescType(tag, theType)
  177.  
  178. #endif
  179.  
  180. #ifdef __cplusplus
  181. };
  182. #endif
  183.